package simulator;

import simulator.hardware.Computer;

/**
 * Scenario is the base interface for all scenarios runnable in a simulation.
 * Includes compatibility with the simulation environment by providing handles
 * to the hardware/sofware abstraction primitive (<code>Computer</code>) and
 * basic metadata (current step, description).
 * 
 * All scenarios also include the <code>run</code> and <code>step</code>
 * methods, for running the entire scenario and stepping through a single
 * timeslice, respectively.
 * 
 * @author David LaPointe
 * @author Kyle Loomis
 */
public interface Scenario
{
   /**
    * Gets the current simulator time, the number of "steps" the scenario has
    * run so far.
    * 
    * @return the current simulator time, or the number of "steps" run so far.
    */
   public int getCurrentStep();

   /**
    * Gets a brief description of the scenario.
    * 
    * @return a brief description of the scenario
    */
   public String getDescription();

   /**
    * Runs the scenario to completion.
    */
   public void run();

   /**
    * Runs the scenario until the specified step, <code>stepNumber</code>.
    * 
    * @param stepNumber
    *           the step the scenario will run to, inclusive
    */
   public void seek(int stepNumber);

   /**
    * Move the scenario forward a single timeslice, or step.
    */
   public void step();

   /**
    * Gets the <code>Computer</code> associated with this <code>Scenario</code>.
    * 
    * @return the <code>Computer</code> associated with this
    *         <code>Scenario</code>.
    * @see Computer
    */
   public Computer getComputer();

   /**
    * Sets the <code>Computer</code> associated with this <code>Scenario</code>.
    * 
    * @param computer
    *           the <code>Computer</code> to associate with this
    *           <code>Scenario</code>.
    */
   public void setComputer(Computer computer);

   /**
    * Sets a brief description for this <code>Scenario</code>.
    * 
    * @param description
    *           the brief description of this <code>Scenario</code>.
    */
   public void setDescription(String description);
}